fix(runtime): distinguish usage limits from auth errors - #2521

#2675 合并后，我重新检查了这个分支，并基于当前 main 重建了它。

#2675 已经解决的是“诊断如何安全传到界面”：ModelAdapter 会保留经过白名单筛选、脱敏和长度限制的 provider 摘要；terminal RuntimeEvent 记录 canonical 失败消息；Runtime Host 将它带入失败 Turn snapshot 和恢复流程；Desktop 复制错误报告时会附上已有的 execution trace。因此我删除了本 PR 旧版本中并行实现的 Runtime Host、Headless、continuity schema 和 diagnostics 改动，没有为了消除冲突而保留重复代码。

还缺的是这条链路之前的语义分类。当前 main 把所有 HTTP 403 都归为 auth，而 #2675 只会为 unknown failure 选用 provider 摘要。所以实测 Kimi 返回 403、error.type = permission_error 时，TUI 仍会把有用的额度说明替换成 Authentication failed。

这一版不猜测 Kimi 的通用 permission_error 具体属于哪一种账户状态：裸 403 保持 unknown、不可重试，并让经过边界处理的 provider 说明到达 TUI/Desktop。只有 provider 给出更强的结构化标识，例如 permission_denied、usage_limit_reached 或 insufficient_quota，才赋予稳定语义。裸 429 的既有速率限制行为保持不变；如果结构化证据明确表明是账户额度问题，则不会把它当成瞬时限流重试。

我加入了实际观察到的 Kimi envelope fixture 和一项 TUI 投影测试。本地验证通过：Runtime 3,316 项（3 项跳过）、CLI 352 项、Desktop typecheck/checks 与 10 项针对性矩阵，以及全仓 lint。没有再次用一个已耗尽额度的真实 Kimi 账户发请求，因此真实账户端到端验证仍是当前边界。

Kimi Code Plan 这个真实场景的前后对比如下。

本 PR 之前，实测 HTTP 403 会被归为认证失败，TUI 显示：

Error: Authentication failed

本 PR 之后，Kimi 的通用 error.type = permission_error 保持为 unknown 且不可重试，TUI 改为显示经过边界处理的 provider 说明：

Error: You've reached your usage limit for this billing cycle. Your quota will be refreshed in the next cycle. To continue now, purchase extra usage or upgrade your plan: https://www.kimi.com/code/#pricing (code=permission_error, status=403)

这里不会因为 message 中出现 “usage limit” 就把错误分类成 UsageLimit。Provider message 只用于展示，不是错误分类的 authority；只有 provider 给出 usage_limit_reached 这类稳定的结构化标识时，Maka 才会赋予 usage_limit 语义。

What this PR solves

The PR distinguishes authentication, permission, billing, usage-limit, rate-limit, and availability failures.

Structured provider identifiers take precedence over HTTP status codes. Bare HTTP 403 responses remain unknown and non-retryable. Existing bare-429 behavior remains unchanged.

The change prevents Kimi permission_error responses from appearing as Authentication failed. Bounded provider explanations can reach TUI and Desktop. Account-limit failures are not retried as transient throttling.

Source of truth and solution scope

The PR extends the shared provider-error classification and ModelAdapter path. It does not create a parallel diagnostic path.

ProviderFailureResult is the shared authority across Runtime normalization, connection tests, Runtime Host projections, telemetry, CLI, TUI, and Desktop. Existing diagnostic transport carries bounded provider summaries through these surfaces.

The solution is the smallest coherent change supported by the diff. The added fields, protocol validation, presentation mappings, and tests preserve classification and bounded-message metadata across connection tests and failed turns.

No safe deletion or simplification is evident without weakening regression coverage or message-safety validation.

Validation and risks

Tests cover structured provider identifiers, nested causes, Kimi plan-limit responses, permission errors, usage limits, billing, authentication, rate limits, availability, retry behavior, bare 401/403 responses, bounded-message propagation, Runtime Host protocol validation, failed-turn projection, TUI, Desktop, CLI, and connection-test presentation.

Reported verification passed for Runtime, Runtime Host, Desktop, typecheck, formatting, diff checks, and reverse-mutation checks. No live request was made against an exhausted Kimi account. Unrelated Computer Use test-harness flakes were reported in CI and tracked separately in issue #3247. Required-check status remains unverified from the available evidence.

Complexity delta

The PR adds:

• One shared ProviderFailureResult authority.
• Structured provider-code extraction across nested envelopes.
• Permission and usage-limit failure classes.
• Bounded provider-message metadata.
• Optional provider-failure fields in connection-test and failed-turn contracts.
• Account-specific recovery guidance.
• Regression and projection tests.

The PR removes:

• Unconditional HTTP 403 authentication classification.
• Status-only classification when structured provider evidence exists.
• Untrusted provider-message rendering.
• Retry treatment for structured account-limit failures.
• Duplicate diagnostic and Runtime Host plumbing from earlier revisions.

The shared authority replaces distributed status-based decisions. The new branches and fields preserve required behavior across several surfaces. The tests increase maintenance work but protect classification precedence, retry behavior, protocol validation, and safe presentation. Total maintenance complexity stays justified.

Review-relevant risks

• User-visible error and recovery behavior changes for provider permission, usage-limit, billing, authentication, and connection-test failures. Material changes require independent human review under repository policy.
• Public contracts change through ProviderFailureResult, ModelFailureKind, ConnectionTestResult, ErrorEvent, and Runtime Host protocol fields. Material public-contract changes require independent human review under repository policy.
• Bounded provider-message handling affects provider-text exposure. Material security or data-exposure changes require independent human review under repository policy.
• Retry behavior changes for structured account-limit errors. Material reliability or operational-policy changes require independent human review under repository policy.
• Runtime Host compatibility epoch RUNTIME_HOST_COMPATIBILITY_EPOCH changes from 25 to 26. Material release or compatibility changes require independent human review under repository policy.
• No licensing or governance effect was identified in the current diff.

Required checks remain unverified from the available evidence. The person performing the merge reviews the final diff. A maintainer makes the final determination.

Walkthrough

The change adds shared provider-failure classification. Runtime, Runtime Host, Desktop, and CLI preserve structured failure details, bounded provider messages, localized explanations, and recovery actions.

Changes

Provider failure flow

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: 🟡 Moderate · up to ff500

The PR improves provider-limit classification, but current failure paths can still misclassify some status-wrapped errors and replace localized CLI/Desktop guidance with less appropriate copy. Merge readiness remains moderate until these bounded correctness and presentation issues are fixed or explicitly accepted.

Sequence Diagram(s)

sequenceDiagram
  participant Provider
  participant Runtime
  participant RuntimeHost
  participant Desktop
  Provider->>Runtime: error response with status and provider code
  Runtime->>Runtime: classify provider failure and bound message
  Runtime->>RuntimeHost: failed turn or connection result
  RuntimeHost->>Desktop: validated providerFailure metadata
  Desktop->>Desktop: localize class or render bounded message

❌ Failed checks (1 warning)

Description

classifyProviderFacts still checks whether arbitrary error text contains abort before evaluating
the new structured provider codes. A provider payload such as type: 'usage_limit_reached' with
wording that the request was aborted is classified as Abort, losing the stable usage-limit reason
and account guidance.

Code

packages/runtime/src/provider-error-classification.ts[R751-755]

+  if (structuredCodes.some((value) => PROVIDER_AUTH_CODES.has(value))) return 'Auth';
+  if (structuredCodes.some((value) => PROVIDER_BILLING_CODES.has(value))) return 'ProviderBilling';
+  if (structuredCodes.some((value) => PROVIDER_PERMISSION_CODES.has(value)))
+    return 'ProviderPermission';
+  if (structuredCodes.some((value) => PROVIDER_USAGE_LIMIT_CODES.has(value))) return 'UsageLimit';

Relevance

●●● Strong

Recent runtime precedent accepts strengthening structured semantic precedence over ambiguous text or
transport evidence.

PR-#2535

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The classifier has an explicit RetryError abort check before normalization, so genuine SDK
cancellation already has a stronger seam. Inside fact classification, however, the pre-existing text
substring check precedes every newly added structured account code despite the same function
documenting weak text heuristics as lower priority.

packages/runtime/src/provider-error-classification.ts[740-758]
packages/runtime/src/provider-error-classification.ts[772-783]
packages/runtime/src/provider-error-classification.ts[371-395]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A weak free-text `abort` match outranks the new stable provider identifiers.

## Issue Context
Move only the textual abort fallback below structured-code classification. Explicit Runtime/AI SDK abort authority remains handled before fact classification, so no new state or branch is needed.

## Fix Focus Areas
- packages/runtime/src/provider-error-classification.ts[740-758]
- packages/runtime/src/provider-error-classification.ts[772-783]
- packages/runtime/src/__tests__/provider-error-classification.test.ts[430-479]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

httpFailure forwards providerFailureResult unchanged even when it contains a generated,
metadata-only message without boundedProviderMessage: true, while decodeProviderFailureResult
rejects every unmarked message. Consequently, a normal bare 401/403/429 connection-test response can
produce a committed, otherwise valid result that violates the connection.test.run protocol
contract and cannot reach Desktop.

Code

packages/runtime/src/test-connection.ts[R439-447]

+  const providerFailure = providerFailureResult({ statusCode, responseBody: errorBody });
  return {
    ok: false,
-    errorMessage: `${statusCode} ${errorBody.slice(0, 200)}`,
+    ...(providerFailure.boundedProviderMessage === true && providerFailure.message !== undefined
+      ? { errorMessage: providerFailure.message }
+      : {}),
    statusCode,
-    errorClass: classifyHttpStatus(statusCode),
+    errorClass: connectionTestErrorClassFromProviderClass(providerFailure.errorClass),
+    providerFailure,

Relevance

●●● Strong

Protocol decoders are treated as strict contracts; forwarding invalid unmarked messages is a
deterministic correctness defect.

PR-#3079
PR-#2674

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The shared producer always generates a summary message when HTTP status metadata is available, but
it adds boundedProviderMessage only when the message contains actual bounded provider wording. The
connection-test HTTP-failure path forwards that complete result unchanged, while the newly added
Runtime Host decoder explicitly rejects the resulting combination of an unmarked diagnostic message,
proving that status-only failures cannot be decoded.

packages/runtime/src/test-connection.ts[435-449]
packages/runtime/src/provider-error-classification.ts[335-350]
packages/runtime-host/src/protocol/connection-effects.ts[437-445]
packages/runtime/src/network/tests/scoped-fetch-transport.test.ts[361-380]
packages/runtime/src/provider-error-classification.ts[320-350]
packages/runtime/src/provider-error-classification.ts[400-416]
packages/runtime/src/connection-effect-outcome.ts[59-77]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Resolve the mismatch between the Runtime producer and Runtime Host decoder: `providerFailureResult({ statusCode, responseBody })` can emit a metadata-only diagnostic `message` without `boundedProviderMessage`, but the protocol currently rejects that shape, preventing connection-test results from being decoded and delivered.

## Issue Context
Preserve the structured class, status, and retry fields. Only a Runtime-marked, bounded provider summary may be presented verbatim, but metadata-only unmarked messages are valid diagnostic data and presentation already refuses to render them verbatim. Consider fixing the closest existing seam in the connection-test HTTP-failure projection or removing the decoder's unnecessary reverse implication, while retaining the rule that `boundedProviderMessage: true` requires a message.

## Fix Focus Areas
- packages/runtime/src/test-connection.ts[435-449]
- packages/runtime-host/src/protocol/connection-effects.ts[437-445]
- packages/runtime/src/provider-error-classification.ts[400-416]
- packages/runtime-host/src/__tests__/connection-effects-protocol.test.ts[183-203]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

Both Desktop connection-test fallbacks ignore ProviderBilling, ProviderPermission, and
UsageLimit, then collapse them through legacy errorClass: 'provider_unavailable'. Structured
account failures without provider message text are consequently displayed as generic service outages
instead of the distinct account meanings this PR introduces.

Code

apps/desktop/src/renderer/app-shell-copy.ts[R61-64]

+    case 'ProviderUnavailable':
+      return copy.provider;
+    default:
+      break;

Relevance

●●● Strong

Structured account failures must retain their distinct UI meanings; recent projection-consistency
fixes are accepted.

PR-#2956

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Runtime maps all three classes to provider_unavailable in the legacy field while preserving the
structured class, but the new Desktop switches handle only Auth, Timeout, RateLimit, Network, and
ProviderUnavailable. Existing conversation copy already contains distinct localized billing,
permission, and usage-limit meanings, so the generic fallback is demonstrably a lost projection
rather than missing source data.

packages/runtime/src/test-connection.ts[456-471]
apps/desktop/src/renderer/app-shell-copy.ts[50-70]
apps/desktop/src/renderer/settings/provider-panel-shared.ts[70-94]
apps/desktop/src/renderer/session-error-presentation.ts[14-30]
apps/desktop/src/renderer/locales/conversation-copy.ts[284-297]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Desktop discards the new structured account classes whenever there is no Runtime-marked provider message.

## Issue Context
Reuse the existing localized account meanings already exposed by the conversation/session-error presentation seam; do not infer from HTTP status or message text. Apply one shared mapping to both connection-test surfaces rather than duplicating another taxonomy.

## Fix Focus Areas
- apps/desktop/src/renderer/app-shell-copy.ts[50-70]
- apps/desktop/src/renderer/settings/provider-panel-shared.ts[70-94]
- apps/desktop/src/renderer/session-error-presentation.ts[14-30]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

A terminal error with boundedProviderMessage: true and an empty message produces a failed Turn
snapshot with the marker but no failureMessage; the decoder accepts it and the projector then
substitutes Turn failed: ... while retaining the marker. This creates an internally inconsistent
provenance claim for the new cross-host snapshot fields.

Code

packages/runtime-host/src/server/canonical-turn-snapshot.ts[R71-72]

        ...(failureMessage ? { failureMessage } : {}),
+        ...(boundedProviderMessage ? { boundedProviderMessage: true } : {}),

Relevance

●● Moderate

The provenance inconsistency is plausible, but no close precedent specifically addresses empty
marked failure messages.

PR-#3079

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Runtime-event error content permits an empty string and a boolean marker. Canonical reconstruction
omits empty failure messages but independently copies the marker, while the new failed-turn decoder
validates those properties independently and the projector copies the marker onto a generated
fallback.

packages/core/src/runtime-event.ts[691-698]
packages/runtime-host/src/server/canonical-turn-snapshot.ts[49-72]
packages/runtime-host/src/protocol/turn.ts[637-666]
packages/runtime-host/src/adapter/session-projector.ts[395-406]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A bounded-provider marker is emitted independently of `failureMessage`. Since an empty terminal error message is omitted from the snapshot, this permits `boundedProviderMessage: true` with no message and later causes the projector to apply the marker to its synthesized fallback.

## Issue Context
Do not add a second provenance mechanism. Reuse the existing `failureMessage` presence check and only propagate the marker when that message is actually present (or reject this inconsistent shape at the decoder as defense in depth).

## Fix Focus Areas
- packages/runtime-host/src/server/canonical-turn-snapshot.ts[49-72]
- packages/runtime-host/src/protocol/turn.ts[637-666]
- packages/runtime-host/src/adapter/session-projector.ts[395-406]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

💡 Did you know, you can show, collapse, or hide each part of a finding: code, evidence, and all

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗